IRIX Base Documentation 2002 November/SGI IRIX Base Documentation 2002 November.iso/usr/share/catman/p_man/cat3p/usinit.z/usinit

Text File | 2002-10-03 | 21.8 KB | 331 lines

UUUUSSSSIIIINNNNIIIITTTT((((3333PPPP))))                                                          UUUUSSSSIIIINNNNIIIITTTT((((3333PPPP))))



NNNNAAAAMMMMEEEE
     _uuuu_ssss_iiii_nnnn_iiii_tttt, _uuuu_ssss_dddd_eeee_tttt_aaaa_cccc_hhhh, _uuuu_ssss_aaaa_dddd_dddd, ______uuuu_tttt_rrrr_aaaa_cccc_eeee, ______uuuu_eeee_rrrr_rrrr_oooo_rrrr - shared arena initialization

CCCC SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     ####iiiinnnncccclllluuuuddddeeee <<<<uuuulllloooocccckkkkssss....hhhh>>>>

     _uuuu_ssss_pppp_tttt_rrrr______tttt _****_uuuu_ssss_iiii_nnnn_iiii_tttt _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_f_i_l_e_n_a_m_e_))))_;;;;

     _iiii_nnnn_tttt _uuuu_ssss_aaaa_dddd_dddd _((((_uuuu_ssss_pppp_tttt_rrrr______tttt _****_u_))))_;;;;

     _vvvv_oooo_iiii_dddd _uuuu_ssss_dddd_eeee_tttt_aaaa_cccc_hhhh _((((_uuuu_ssss_pppp_tttt_rrrr______tttt _****_u_))))_;;;;

     _eeee_xxxx_tttt_eeee_rrrr_nnnn _iiii_nnnn_tttt ______uuuu_eeee_rrrr_rrrr_oooo_rrrr_;;;;

     _eeee_xxxx_tttt_eeee_rrrr_nnnn _iiii_nnnn_tttt ______uuuu_tttt_rrrr_aaaa_cccc_eeee_;;;;

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     _uuuu_ssss_iiii_nnnn_iiii_tttt is used to initialize a shared arena from which related or
     unrelated processes may allocate and share semaphores, locks and memory.
     Locks, semaphores and memory can then be allocated using the _u_s_p_t_r__t
     returned by _uuuu_ssss_iiii_nnnn_iiii_tttt.  More than one call can be made to _uuuu_ssss_iiii_nnnn_iiii_tttt to create
     separate _a_r_e_n_a_s of locks and semaphores.  In fact, calls to _uuuu_ssss_iiii_nnnn_iiii_tttt may be
     made on behalf of a process: when _ssss_pppp_rrrr_oooo_cccc(2) is called, an arena containing
     the locks and semaphores for libc is created; when _mmmm______ffff_oooo_rrrr_kkkk(3P) is called,
     an arena is set up to control the spawned tasks.  _uuuu_ssss_iiii_nnnn_iiii_tttt uses a file in
     the file system to name the arena.  This name can then be used by
     unrelated processes to access the arena.

     _uuuu_ssss_iiii_nnnn_iiii_tttt creates a file, _ffff_iiii_llll_eeee_nnnn_aaaa_mmmm_eeee, and maps it into the caller's space via
     _mmmm_mmmm_aaaa_pppp(2).  The file is mapped using the MMMMAAAAPPPP____AAAAUUUUTTTTOOOOGGGGRRRROOOOWWWW option to _mmmm_mmmm_aaaa_pppp(2)
     (see _uuuu_ssss_cccc_oooo_nnnn_ffff_iiii_gggg(3P) for ways to alter this behavior).  By default the file
     is not removed when the last process using it is finished.  This behavior
     can be modified somewhat via _uuuu_ssss_cccc_oooo_nnnn_ffff_iiii_gggg(3P).  File locks (see _ffff_cccc_nnnn_tttt_llll(2)) are
     used to prevent conflicting accesses to this area during the _uuuu_ssss_iiii_nnnn_iiii_tttt call.
     There is no way to tell the id of the process that actually created the
     arena.  The file name given to _uuuu_ssss_iiii_nnnn_iiii_tttt may be an NFS mounted file, however
     it is important to understand that NFS does not guarantee write
     synchronization across multiple machines - thus if all users of an arena
     are running on a single machine and using an NFS mounted file as the
     arena, then all will work fine. If multiple users running on different
     machines all access the same arena file, the arena will be corrupted.

     Gaining access to a particular arena for the purpose of sharing locks,
     semaphores, and memory is dependent on how the processes are related and
     how the arena was initialized.  If the arena was initialized (which is
     the default) without the UUUUSSSS____SSSSHHHHAAAARRRREEEEDDDDOOOONNNNLLLLYYYY option to _uuuu_ssss_cccc_oooo_nnnn_ffff_iiii_gggg(3P) then any
     process with the appropriate permissions can join the arena at any time
     by calling _uuuu_ssss_iiii_nnnn_iiii_tttt with _f_i_l_e_n_a_m_e.  These processes may be unrelated,
     related via _ffff_oooo_rrrr_kkkk, related via _ssss_pppp_rrrr_oooo_cccc sharing file descriptors, or related
     via _ssss_pppp_rrrr_oooo_cccc not sharing file descriptors.





                                                                        PPPPaaaaggggeeee 1111






UUUUSSSSIIIINNNNIIIITTTT((((3333PPPP))))                                                          UUUUSSSSIIIINNNNIIIITTTT((((3333PPPP))))



     If the arena was initialized with the UUUUSSSS____SSSSHHHHAAAARRRREEEEDDDDOOOONNNNLLLLYYYY option to
     _uuuu_ssss_cccc_oooo_nnnn_ffff_iiii_gggg(3P) then the file specified by _f_i_l_e_n_a_m_e is unlinked.  This means
     that the only processes that can join the arena must somehow already have
     a handle for that arena (i.e. the arena must already be mapped into their
     address space).  Unrelated processes, processes spawned via _ffff_oooo_rrrr_kkkk before
     the arena was initialized, and process spawned via _ssss_pppp_rrrr_oooo_cccc and not sharing
     file descriptors, can never get the appropriate handle.  If a process
     with the above characteristics calls _uuuu_ssss_iiii_nnnn_iiii_tttt with _f_i_l_e_n_a_m_e a NEW arena
     will be created that has no relation to any other process's arena.
     Processes that have the correct handle are automatically made 'members'
     of the arena the first time they use a lock or semaphore.  They may
     choose to call _uuuu_ssss_aaaa_dddd_dddd explicitly so that any potential errors are detected
     at initialization time, rather than the first time a lock or semaphore is
     used.  Previous versions of this manual page suggested calling _uuuu_ssss_iiii_nnnn_iiii_tttt
     rather than _uuuu_ssss_aaaa_dddd_dddd.  This still works for any arena except one using
     _////_dddd_eeee_vvvv_////_zzzz_eeee_rrrr_oooo.  _uuuu_ssss_aaaa_dddd_dddd will work for any arena.

     Certain attributes of the newly created arena may be set prior to the
     call to _uuuu_ssss_iiii_nnnn_iiii_tttt by _uuuu_ssss_cccc_oooo_nnnn_ffff_iiii_gggg(3P).  These include the maximum number of
     users that can simultaneously access the arena, the maximum size the
     arena can grow to, the access permissions on the arena, the type of
     debugging enabled, and where in the caller's address space the arena will
     be attached.  The overall size will limit how many locks and semaphores
     may be allocated and how much space in the arena is left over for the
     user to allocate via _uuuu_ssss_mmmm_aaaa_llll_llll_oooo_cccc(3P).  In addition to the arena header,
     basic lock, and semaphore data structures, all history, metering and
     debug structures are also allocated via _uuuu_ssss_mmmm_aaaa_llll_llll_oooo_cccc(3P) from the arena.  The
     default size is 64K, and the default number of users is 8.

     When called, _uuuu_ssss_iiii_nnnn_iiii_tttt attempts to determine whether the arena described by
     _f_i_l_e_n_a_m_e is active (i.e. whether any other processes are currently using
     it).  This determination is made by checking whether any file locks are
     currently active on the file.  If so, the caller registers its file lock
     and merely 'joins' the collection of processes using that arena.  If
     there are no file locks, the caller re-initializes the entire arena.
     Problems can result if a process that did not call _uuuu_ssss_iiii_nnnn_iiii_tttt is still
     accessing the arena (namely a child of a _ssss_pppp_rrrr_oooo_cccc whose parent has died)
     when a new process attempts to join.  The new process will find no file
     locks and re-initialize the arena, thus destroying any state the first
     process had.  This problem can be solved by having all processes register
     with the arena by calling _uuuu_ssss_aaaa_dddd_dddd.  Previous versions of this manual page
     suggested calling _uuuu_ssss_iiii_nnnn_iiii_tttt rather than _uuuu_ssss_aaaa_dddd_dddd.  This still works for any
     arena except one using _////_dddd_eeee_vvvv_////_zzzz_eeee_rrrr_oooo.  _uuuu_ssss_aaaa_dddd_dddd will work for any arena.

     As a special case, _////_dddd_eeee_vvvv_////_zzzz_eeee_rrrr_oooo can be passed as the value for _f_i_l_e_n_a_m_e.
     Since _////_dddd_eeee_vvvv_////_zzzz_eeee_rrrr_oooo by definition is private to the process that opens it,
     this is useful only for share group members that are sharing file
     descriptors.  The space for _////_dddd_eeee_vvvv_////_zzzz_eeee_rrrr_oooo comes from the logical swap pool
     (see _ssss_wwww_aaaa_pppp(1M)) rather than from the file system.  Depending on the system
     configuration there may be more space in the logical swap pool than on a
     file system.  The logical swap pool is also a limited resource and _uuuu_ssss_iiii_nnnn_iiii_tttt
     may fail due to lack of logical swap.  It is possible to delay allocation



                                                                        PPPPaaaaggggeeee 2222






UUUUSSSSIIIINNNNIIIITTTT((((3333PPPP))))                                                          UUUUSSSSIIIINNNNIIIITTTT((((3333PPPP))))



     of logical swap (much like the _MMMM_AAAA_PPPP______AAAA_UUUU_TTTT_OOOO_GGGG_RRRR_OOOO_WWWW option delays growth of
     files) by using the _CCCC_OOOO_NNNN_FFFF______AAAA_UUUU_TTTT_OOOO_RRRR_EEEE_SSSS_VVVV option of _uuuu_ssss_cccc_oooo_nnnn_ffff_iiii_gggg(3P).

     _uuuu_ssss_iiii_nnnn_iiii_tttt and the other lock and semaphore routines normally perform their
     functions in silence.  For a verbose 'trace' of what is being done, the
     global flag ____uuuuttttrrrraaaacccceeee may be set to non-zero.  In addition, if the
     environment variable UUUUSSSSTTTTRRRRAAAACCCCEEEE is set, _uuuu_ssss_iiii_nnnn_iiii_tttt will automatically set
     ____uuuuttttrrrraaaacccceeee.  The tracing information consists of two types of messages -
     trace and error.  Error type messages can be enabled independently from
     tracing messages by setting the global flag ____uuuueeeerrrrrrrroooorrrr.  In addition, if the
     environment variable UUUUSSSSEEEERRRRRRRROOOORRRR is set, _uuuu_ssss_iiii_nnnn_iiii_tttt will automatically set
     ____uuuueeeerrrrrrrroooorrrr.  All messages are printed on _ssss_tttt_dddd_eeee_rrrr_rrrr.  This may aid in debugging
     the various error returns.

     An arena, once established, must reside at the same virtual address in
     each process that attaches to it.  This implies that if more than one
     process is creating an arena, the creating processes must impose the
     appropriate ordering.  The following scenario will lead to such an
     ordering problem:  process A creates arena A_arena, and process B creates
     arena B_arena.  Then process A attempts to attach (via _uuuu_ssss_iiii_nnnn_iiii_tttt) to
     B_arena.  _uuuu_ssss_iiii_nnnn_iiii_tttt will most probably fail in this case since the virtual
     address for both arenas will probably be identical.  One way around this
     ordering problem is to use _uuuu_ssss_cccc_oooo_nnnn_ffff_iiii_gggg(3P) to manually set the address where
     the arena should be attached.  It is then only important that all arena
     creating processes agree on the addresses for each of the arenas.
     Another easy way around this problem is to have all arenas created by one
     process.

     A process may detach an arena by calling _uuuu_ssss_dddd_eeee_tttt_aaaa_cccc_hhhh.  This call will unmap
     and close all the relevant file descriptors.  It does not check for any
     outstanding locks, allocated memory, etc.  _uuuu_ssss_dddd_eeee_tttt_aaaa_cccc_hhhh will not close any
     pollable semaphores, this must be done before calling _uuuu_ssss_dddd_eeee_tttt_aaaa_cccc_hhhh.  For
     _ssss_pppp_rrrr_oooo_cccc processes sharing file descriptors, if one member calls _uuuu_ssss_dddd_eeee_tttt_aaaa_cccc_hhhh
     then the arena is detached for the entire share group.  There is no
     protection for multiple members of a share group simultaneously calling
     _uuuu_ssss_dddd_eeee_tttt_aaaa_cccc_hhhh, this should not be done.

     If _uuuu_ssss_iiii_nnnn_iiii_tttt fails, it is a good idea to set the tracing variable ____uuuuttttrrrraaaacccceeee to
     1 or set the environment variable UUUUSSSSTTTTRRRRAAAACCCCEEEE).  This will provide more
     descriptive error messages.

     _uuuu_ssss_iiii_nnnn_iiii_tttt or _uuuu_ssss_aaaa_dddd_dddd  will fail if one or more of the following are true:

     _EEEE_AAAA_CCCC_CCCC_EEEE_SSSS    The _f_i_l_e_n_a_m_e argument could not be opened or created for
               read/write.

     _EEEE_NNNN_OOOO_SSSS_PPPP_CCCC    The file specified by _f_i_l_e_n_a_m_e could not be grown to the
               specified size.

     _EEEE_NNNN_OOOO_MMMM_EEEE_MMMM    There is not enough space in the arena to allocate the initial
               set of required locks and semaphores.  The size of the arena
               may be manipulated with _uuuu_ssss_cccc_oooo_nnnn_ffff_iiii_gggg(3P).



                                                                        PPPPaaaaggggeeee 3333






UUUUSSSSIIIINNNNIIIITTTT((((3333PPPP))))                                                          UUUUSSSSIIIINNNNIIIITTTT((((3333PPPP))))



     _EEEE_BBBB_UUUU_SSSS_YYYY     The caller already has mapped virtual space at the address
               requested with the _CCCC_OOOO_NNNN_FFFF______AAAA_TTTT_TTTT_AAAA_CCCC_HHHH_AAAA_DDDD_DDDD_RRRR option of _uuuu_ssss_cccc_oooo_nnnn_ffff_iiii_gggg.

     _EEEE_BBBB_UUUU_SSSS_YYYY     The caller already has mapped virtual space at the address
               required by the arena when attempting to join the arena.

     _EEEE_NNNN_XXXX_IIII_OOOO     One or both of the two semaphore device files, ////ddddeeeevvvv////uuuusssseeeemmmmaaaa and
               ////ddddeeeevvvv////uuuusssseeeemmmmaaaacccclllloooonnnneeee, do not exist, or the device is not configured
               into the system.

     _EEEE_IIII_NNNN_VVVV_AAAA_LLLL    This error is returned if the version the currently attaching
               process was compiled with is incompatible with the version
               compiled into the creator of the arena.

     _EEEE_NNNN_OOOO_LLLL_CCCC_KKKK    There are no more file locks available because the system
               maximum {_FFFF_LLLL_OOOO_CCCC_KKKK______MMMM_AAAA_XXXX} [see _iiii_nnnn_tttt_rrrr_oooo(2)], has been exceeded.

     _EEEE_NNNN_OOOO_LLLL_CCCC_KKKK    _f_i_l_e_n_a_m_e is in an NFS-mounted directory, and either the NFS
               lock daemon, _llll_oooo_cccc_kkkk_dddd(1M) is not running (either on the server or
               client) or the maximum number of file locks that _llll_oooo_cccc_kkkk_dddd can
               handle has been exceeded.

     _EEEE_AAAA_GGGG_AAAA_IIII_NNNN    _f_i_l_e_n_a_m_e was set to _////_dddd_eeee_vvvv_////_zzzz_eeee_rrrr_oooo and there isn't enough logical
               swap space to map the requested size arena.

     Errors may also be the result of a _mmmm_mmmm_aaaa_pppp(2) or a _ffff_cccc_nnnn_tttt_llll(2) system call.

SSSSEEEEEEEE AAAALLLLSSSSOOOO
     _ffff_cccc_nnnn_tttt_llll(2), _mmmm_mmmm_aaaa_pppp(2), _ssss_pppp_rrrr_oooo_cccc(2), _aaaa_cccc_qqqq_uuuu_iiii_rrrr_eeee______llll_oooo_cccc_kkkk(3), _bbbb_aaaa_rrrr_rrrr_iiii_eeee_rrrr(3P), _oooo_ssss_eeee_rrrr_rrrr_oooo_rrrr(3C),
     _uuuu_ssss_cccc_aaaa_ssss_iiii_nnnn_ffff_oooo(3P), _uuuu_ssss_cccc_oooo_nnnn_ffff_iiii_gggg(3P), _uuuu_ssss_gggg_eeee_tttt_iiii_nnnn_ffff_oooo(3P), _uuuu_ssss_mmmm_aaaa_llll_llll_oooo_cccc(3P), _uuuu_ssss_nnnn_eeee_wwww_llll_oooo_cccc_kkkk(3P),
     _uuuu_ssss_nnnn_eeee_wwww_ssss_eeee_mmmm_aaaa(3P).

DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
     Upon successful completion, _uuuu_ssss_iiii_nnnn_iiii_tttt returns a pointer to a _u_s_p_t_r__t
     structure. Otherwise, a value of NULL is returned and _eeee_rrrr_rrrr_nnnn_oooo is set to
     indicate the error.

     Upon successful completion, _uuuu_ssss_aaaa_dddd_dddd returns zero.  Otherwise a value of
     negative one is returned and _eeee_rrrr_rrrr_nnnn_oooo is set to indicate the error.

BBBBUUUUGGGGSSSS
     _uuuu_ssss_iiii_nnnn_iiii_tttt string compares _f_i_l_e_n_a_m_e with the names of existing arenas in the
     calling process.  If it finds a match, it assumes that the arena already
     exists and that the caller has already (due to already having called
     _uuuu_ssss_iiii_nnnn_iiii_tttt with the same _f_i_l_e_n_a_m_e or due to being related to the process that
     created the arena) mapped in the arena.  This can cause unexpected
     results if the application has code along the following lines:

            filename = strdup(template);
            mktemp(filename);
            arena = usinit(filename);
            (fork, exec, communicate file name to other process,



                                                                        PPPPaaaaggggeeee 4444






UUUUSSSSIIIINNNNIIIITTTT((((3333PPPP))))                                                          UUUUSSSSIIIINNNNIIIITTTT((((3333PPPP))))



            it attaches to arena)
            unlink(filename);

     The second time this is done, _mmmm_kkkk_tttt_eeee_mmmm_pppp could come up with the exact same
     name file as before (since the first one was unlinked).  When _uuuu_ssss_iiii_nnnn_iiii_tttt
     compares the name to the names of already existing and mapped arenas, it
     will find a match and NOT create a new arena.  Certainly, in this case,
     not the desired result.

WWWWAAAARRRRNNNNIIIINNNNGGGGSSSS
     Currently, it is not possible to create a shared arena that can be used
     by programs of differing ABIs. This means that o32, N32, and N64 programs
     cannot share an arena.  For primitives that can be shared between 32-bit
     and 64-bit processes see _aaaa_bbbb_iiii_llll_oooo_cccc_kkkk(3P) and _tttt_eeee_ssss_tttt______aaaa_nnnn_dddd______ssss_eeee_tttt(3P).









































                                                                        PPPPaaaaggggeeee 5555